home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / c / dice-3.16.lha / doc / _MAIN.DOC next >
Text File  |  1994-02-13  |  4KB  |  107 lines
  1.  
  2.              USING THE _MAIN ENTRY POINT
  3.  
  4.     DICE uses a general startup code module that supports CLI programs,
  5.     workbench startup, residentable code, and custom configurations
  6.     such as compiling a dos handler.
  7.  
  8.     To this end, DICE relies heavily on its AUTOINIT capability to
  9.     automatically bring in code during linking to perform appropriate
  10.     operations.  For example, if you use floating point, DICE will
  11.     automatically bring in routines to open and close the floating point
  12.     libraries.    If you do NOT use floating point, these routines are NOT
  13.     brought in.
  14.  
  15.     You may have read about DICE's ability to automatically open the
  16.     amiga's libraries, accomplished by you, the programmer, simply making
  17.     the library calls without declaring the library base variable and
  18.     DICE automatically bringing in appropriate code during linking
  19.     to open and close those libraries not explcitly declared.  DICE uses
  20.     this feature not only for the floating point libraries, but for
  21.     DOS.LIBRARY as well.
  22.  
  23.     DICE also uses the general autoinit capability to bring in code to
  24.     support the workbench.  Specifically, to wait for and retrieve the
  25.     workbench message passed to the task on its message port. This message
  26.     MUST be pulled off the port before even DOS.LIBRARY can be openned.
  27.  
  28.     Normally, when you use the main() entry point, C.LIB's _main will be
  29.     brought in.  This causes an implicit reference causing ALIB/WBMAIN.A to
  30.     be brought in as autoinit code which is called by c.a before doing
  31.     anything that requires DOS.  In otherwords, workbench processing is
  32.     done automatically and wbmain(msg) is called (which you have to
  33.     supply).
  34.  
  35.     But when you overide the _main() entry point with your own, things
  36.     work differently:
  37.  
  38.     (1) DOS.LIBRARY is now openned automatically only if you makes calls
  39.     that need it.  (i.e. you don't have to worry about it)
  40.  
  41.     (2) STDIO's stdin, stdout, and stderr are not set up, but you can
  42.     still use STDIO on FILE *'s that you explicitly fopen().
  43.  
  44.     (3) DESCRIPTORS 0, 1, and 2 are not set up but you can still use
  45.     low level open(), read(), write(), etc... calls for descriptors
  46.     you open yourself.
  47.  
  48.     (4) MEMORY MANAGEMENT still works fine
  49.  
  50.     (5) WORKBENCH PROCESSING WILL NOT BE DONE BY DEFAULT, there is
  51.     no wbmain() and autoinit code normally brought in by C.LIB's
  52.     _main() to WaitPort()/GetMsg() the workbench message (if
  53.     workbench startup is detected) will NOT be brought in by
  54.     default.
  55.  
  56.               HOW DO I HAVE A _MAIN FOR PROGRAMS
  57.             RUN FROM THE WORKBENCH?
  58.  
  59.     The answer is, a simple trick.  You must make a dummy reference
  60.     by having the following dummy code in your program:
  61.  
  62.     routing_that_is_never_called()
  63.     {
  64.         _waitwbmsg();
  65.     }
  66.  
  67.     NEVER CALL THIS PROCEDURE!    It's only the reference that counts,
  68.     because ALIB/WBMAIN.A which contains _waitwbmsg() brings it in
  69.     as autoinit code which is run automatically by C.O
  70.  
  71.     The end result is that autoinit code will WaitPort()/GetMsg()
  72.     the workbench message before calling your _main().
  73.  
  74.     To process this message your _main() must check the _WBMsg variable.
  75.     If this variable is non-NULL, the program was started from the
  76.     workbench.    If it is NULL the program was started from a CLI.  Note
  77.     that the arguments (len, arg) passed to _main() are ONLY VALID FOR
  78.     CLI RUN PROGRAMS.  They will contain garbage for workbench run
  79.     programs.
  80.  
  81.     You do NOT need to ReplyMsg() the workbench message on exit, that
  82.     is done automatically.  In fact, you should NEVER attempt to
  83.     return _WBMsg yourself, the return must be synced up to the exit
  84.     with a Forbid() that is ensured to not be broken only if done by
  85.     C.O's _exit() call.
  86.  
  87.  
  88.         WHY ISN'T THE WORKBENCH CHECKED FOR BY DEFAULT
  89.          WHEN _main() is OVERRIDEN BY THE PROGRAMMER?
  90.  
  91.     The answer is, to suport custom processes and tasks.  A custom
  92.     process created with CreateProc() or CreateNewProc() (2.0) looks
  93.     just like a workbench process, but no message will be sent over
  94.     the port.  Thus, if DICE were to do workbench processing by
  95.     default it would incorrectly handle custom processes.
  96.  
  97.  
  98.             DO YOU REALLY WANT TO USE _main() ?
  99.  
  100.     No, you do not.  I strongly suggest that you use the standard
  101.     main() and wbmain() entry points for all normal programs.
  102.  
  103.     The ONLY time you *need* to use _main() is when you are developing
  104.     specialized programs such as DOS handlers, devices, and libraries.
  105.  
  106.  
  107.